<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Parametrised Scenarios</title>
</head>

<body>

<h2>Parametrised Scenarios</h2>

<p>Story writers often find themselves repeating scenarios, or parts
thereof, by simply changing some parameter values. These are ideal
candidates for using JBehave's parametrisation features. Let's look at
the example:</p>

<pre class="brush: bdd">
    Given a stock of symbol STK1 and a threshold of 10.0
    When the stock is traded at 5.0
    Then the alert status should be OFF
    When the stock is traded at 11.0
    Then the alert status should be ON
</pre>

<p>We notice that two lines are repeated and identical but for the
values. We can then rewrite this scenario as:</p>

<script type="syntaxhighlighter" class="brush: bdd">
<![CDATA[
    Given a stock of <symbol> and a <threshold>
    When the stock is traded at <price>
    Then the alert status should be <status>
    
    Examples:     
    |symbol|threshold|price|status|
    |STK1|10.0|5.0|OFF|
    |STK1|10.0|11.0|ON|
]]>
</script>

<p>The <b>Examples:</b> keyword signals that the entire scenario is
parametrised and should be repeated for as many times as there are data
rows in the examples table. At each execution, the named parameters are
taken from the corresponding row.</p>

<p>One important difference to underline in using table examples is
that they require <a href="parameter-injection.html">named
parameters</a> for the step candidates to be matched to Java methods. The
named parameters allow the parameters to be injected using the table row
values with the corresponding header name, instead of being extracted
from the annotation pattern match. As such, <b>the step annotation
pattern must hold the verbatim textual step</b>, e.g.:</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
    @Given("a stock of <symbol> and a <threshold>")
    public void aStock(@Named("symbol") String symbol, @Named("threshold") double threshold) {
        // ...
    }
]]>
</script>

<p>Also note that while the characters delimiting the parameter
names in the regex pattern are purely conventional - they only serve the
purpose of matching the step method in a readable manner - the use of
the angle brackets is required as it is used to replace the name with
the value in the reporting.</p>

<p>It is also important to note that the same (<code>@Named</code>-annotated)
methods can match steps that are executed both as standalone or via
examples table, provided that both regex patterns are configured, one as
the main pattern and one as an alias:</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
    @Given("a stock of symbol $symbol and a threshold of $threshold") // standalone
    @Alias("a stock of <symbol> and a <threshold>") // examples table
    public void aStock(@Named("symbol") String symbol, @Named("threshold") double threshold) {
        // ...
    }
]]>
</script>

<p>Moreover, the examples table alias can happily co-exists with
other standalone aliases:</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
    @Given("a stock of symbol $symbol and a threshold of $threshold") // standalone
    @Aliases(values={"a stock with a symbol of $symbol and a threshold of $threshold", // a standalone alias
                     "a stock of <symbol> and a <threshold>"}) // an examples table alias
    public void aStock(@Named("symbol") String symbol, @Named("threshold") double threshold) {
        // ...
    }
]]>
</script>

<h2 id="parameter_controls">Custom parameter delimiters</h2>

<p>The parameter name delimiters are purely conventional.  The step matching works just as well if other delimiters - e.g. [] - are used, 
provided the patterns are updated accordingly:
</p>
<script type="syntaxhighlighter" class="brush: bdd">
<![CDATA[
    Given a stock of [symbol] and a [threshold]
    When the stock is traded at [price]
    Then the alert status should be [status]
    
    Examples:     
    |symbol|threshold|price|status|
    |STK1|10.0|5.0|OFF|
    |STK1|10.0|11.0|ON|
]]>
</script>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
    @Given("a stock of [symbol] and a [threshold]")
    public void aStock(@Named("symbol") String symbol, @Named("threshold") double threshold) {
        // ...
    }
]]>
</script>

<p>The only thing we need to do is to tell the <a
    href="javadoc/core/org/jbehave/core/steps/StepCreator.html">StepCreator</a> to use the custom parameter name delimiters when replacing the parameter value. 
    We do this by configuring a custom instance of <a
    href="javadoc/core/org/jbehave/core/steps/ParameterControls.html">ParameterControls</a>:
<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
    new MostUsefulConfiguration()
            .useParameterControls(new ParameterControls().useNameDelimiterLeft("[").useNameDelimiterRight("]"));
]]>
</script>

<h2 id="by_name_delimiters">Parametrisation by name delimiters</h2>

<p>An alternative way to annotations in specifying the named parameters, is to leverage the name delimiters themselves.  Going back to our example:</p>

<script type="syntaxhighlighter" class="brush: bdd">
<![CDATA[
    Given a stock of <symbol> and a <threshold>
    When the stock is traded at <price>
    Then the alert status should be <status>
    
    Examples:     
    |symbol|threshold|price|status|
    |STK1|10.0|5.0|OFF|
    |STK1|10.0|11.0|ON|
]]>
</script>

<p>We can configure JBehave to interpret the name contained between the delimiters as the parameter name and look it up in the parameters provided by the examples table.
The default behaviour of parameter lookup is overridden via the  <a
    href="javadoc/core/org/jbehave/core/steps/ParameterControls.html">ParameterControls</a>:
</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
    new MostUsefulConfiguration()
            .useParameterControls(new ParameterControls().useDelimiterNamedParameters(true));
]]>
</script>

<p>In this mode, the step method would look much simplified:</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
    @Given("a stock of $symbol and a $threshold")
    public void aStock(String symbol, double threshold) {
        // ...
    }
]]>
</script>

<span class="followup">Starting from version 4.0, the use of delimiter named parameters is the default behaviour.
</span>

<p>Another use case of name delimited parameters is to reuse the same step for different parameter values (with different names), e.g.:</p>

<script type="syntaxhighlighter" class="brush: bdd">
<![CDATA[
    Given a stock of <symbol> and a <threshold>
    And a stock of <alternate_symbol> and a <threshold>
    
    Examples:     
    |symbol|alternate_symbol|threshold|
    |STK1|ALT1|1.0|
]]>
</script>

<p>Both steps would be matched by the method:</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
    @Given("a stock of symbol $symbol") 
    public void aStock(String symbol) {
        // ...
    }
]]>
</script>

<h2 id="external_resources">Loading parameters from an external resource</h2>

<p>The parameters table can also be loaded from an external
resource, be it a classpath resource or a URL.</p>
<script type="syntaxhighlighter" class="brush: bdd">
<![CDATA[
    Given a stock of <symbol> and a <threshold>
    When the stock is traded at <price>
    Then the alert status should be <status>
    
    Examples: 
    org/jbehave/examples/trader/stories/trades.table    
]]>
</script>

<p>We need to enable the parser to find the resource with the appropriate resource loader configured via the <a
    href="javadoc/core/org/jbehave/core/model/ExamplesTableFactory.html">ExamplesTableFactory</a>:
<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
    new MostUsefulConfiguration()
            .useStoryParser(new RegexStoryParser(new ExamplesTableFactory(new LoadFromClasspath(this.getClass()))))
]]>
</script>


<div class="clear">
<hr />
</div>

</body>
</html>